ATSUCreateTextLayoutWithTextHandle

OSStatus ATSUCreateTextLayoutWithTextHandle (
                     UniCharArrayHandle iText,
                     UniCharArrayOffset iTextOffset,
                     UniCharCount iTextLength,
                     UniCharCount iTextTotalLength,
                     ItemCount iNumberOfRuns,
                     UniCharCount iRunLengths[],
                     ATSUStyle iStyles[],
                     ATSUTextLayout *oTextLayout);

iText

A pointer of type UniCharArrayHandle. Pass a handle that points to the beginning of a text buffer. Note that ATSUI expects the buffer to contain Unicode text. Your application is responsible for allocating the memory associated with this handle. ATSUI functions that need to access text referenced by this handle will return the handle to its original state (locked or unlocked) upon function completion.

iTextOffset

A value of type UniCharArrayOffset. Pass the edge offset in backing store memory that corresponds to the beginning of range of text that you want ATSUI to perform layout operations on. If you want the range of text to start at the beginning of the text buffer, you should pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If you want the range of text to cover the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iTextLength parameter. If the specified range of text is outside the text buffer, ATSUCreateTextLayoutWithTextHandle returns the result code kATSUInvalidTextRangeErr.

iTextLength

A value of type UniCharCount. Pass the length of the range of text that you want ATSUI to perform layout operations on. If you want the range of text to span the end of the text buffer, you should pass the constant kATSUToTextEnd, described in Text Length Constant. If you want the range of text to cover the entire text buffer, pass kATSUToTextEnd in this parameter and kATSUFromTextBeginning in the iTextOffset parameter. If the specified range of text is outside the text buffer, ATSUCreateTextLayoutWithTextHandle returns the result code kATSUInvalidTextRangeErr.

iTextTotalLength

A value of type UniCharCount. Pass the length of the text buffer. This value should be greater than the range of text you passed in the iTextOffset and iTextLength parameters, unless you want to perform layout operations on the entire text buffer.

iNumberOfRuns

The number of style runs to assign to the text layout object. This should be equivalent to the number of elements in the iRunLengths and iStyles arrays.

iRunLengths

An array of values of type UniCharCount. Each element in the array must contain a style run length that corresponds to a style object in the iStyles array. You can pass kATSUToTextEnd for the last style run length if you want it to extend to end of the text buffer. If the sum of the lengths is less than the total length of the text buffer (the iTextLength parameter), the remaining characters are assigned to the last style run.

iStyles

An array of references of type ATSUStyle. Each element in the array must contain a valid style object that corresponds to a style run length in the iRunLengths array.

oTextLayout

A pointer to a reference of type ATSUTextLayout. On return, the newly-created text layout object. You cannot pass NULL for this parameter.

function result

A result code. See Result Codes.

DISCUSSION

The ATSUCreateTextLayoutWithTextHandle function creates a text layout object with style runs, a handle to associated text, and default text layout attribute values. The default text layout attribute values are described in Table C-2. You can create a text layout object that contains a pointer to associated text by calling the function ATSUCreateTextLayoutWithTextHandle.

Most functions that operate on text layout objects perform these operations on the range of text that you specify in the iTextOffset and iTextLength parameters. Typically, this is a subrange of the entire text buffer. If this range is shorter than the entire text buffer, the text layout object will scan the remaining text to get the full context for bidirectional processing and other information about the text.

You are responsible for updating the memory location of the text associated with a text layout object whenever the user inserts, deletes, or moves text. To determine the current text memory location, call the function ATSUGetTextLocation.

SPECIAL CONSIDERATIONS

ATSUCreateTextLayoutWithTextHandle allocates memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.